home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Archives / StartupTools / PKludge010.lzh / PKludge / PKludge.doc < prev    next >
Text File  |  1992-11-03  |  11KB  |  265 lines
  1.  
  2. NAME
  3.  
  4.    PKludge     ("Promotion Kludge", an AmigaDos 3.0 commodity)
  5.  
  6.  
  7. AUTHOR, VERSION & COPYRIGHT
  8.  
  9.    Steve Koren
  10.    Version 1.0, November 1992
  11.  
  12.    Requires AmigaDos 3.0 or later
  13.  
  14.    PKludge is copyrighted freeware.  It may be distributed on PD disk
  15.    collections costing no more per disk than the price of a current Fish
  16.    disk.  PKludge may be uploaded to BBS systems.  It may not be sold for
  17.    a profit or modified without permission of the author.  However, you
  18.    are free to give it away to friends, etc.
  19.  
  20.  
  21. SYNOPSIS
  22.  
  23.    PKludge [ CX_PRIORITY=n ] [ PROMOTE=string ]
  24.  
  25.    Promotion string is in the following format:
  26.       <title>/<o_mode>=<n_mode>/<left>/<top>/<width>/<height>/<oscan>
  27.    Where:
  28.       <title>   = Screen title, or "-" for "don't care".
  29.       <o_mode>  = Old screen mode, from display database, or "-"
  30.       <left>    = New screen left edge, or "-" for unchanged
  31.       <top>     = New screen top edge, or "-" for unchanged
  32.       <width>   = New screen width, or "-" for unchanged
  33.       <height>  = New screen height, or "-" for unchanged
  34.       <oscan>   = TEXT, STANDARD, MAX, VIDEO, or "-" for unchanged
  35.  
  36.  
  37. FUNCTION
  38.  
  39.    Screen promotion hack for AmigaDos 3.0 or later.  Promotes any graphics
  40.    mode or named screen to any other, optionally setting size and
  41.    position.  Please read the rest of this documentation for details.
  42.  
  43.  
  44. DESCRIPTION
  45.    
  46.    AmigaDos 3.0 on the Amiga 4000 supports many graphics modes which are
  47.    selected from a display database.  This gives the system significant
  48.    flexibility for defining new display modes.  However, there are a few
  49.    problems with this scheme given the current state of some software:
  50.  
  51.       P1. Some old software is not smart enough to use the display
  52.           database, but can still cope with any sized screen.  A good
  53.           example of this is Excellence! 2.0.
  54.  
  55.       P2. If OS 3.0 mode promotion is used, screens are always promoted to
  56.           like resolutions.  Sometimes this is not desirable.
  57.  
  58.       P3. Multisync monitors must re-sync when displaying screens of
  59.           different scan rates.  Sometimes it is desirable to display, for
  60.           example, 640x400 NTSC:High Res Laced screens on a
  61.           Super72:Super-High Res Laced screen in the same 640x400
  62.           resolution in order to prevent monitor re-sync during screen
  63.           shuffles.
  64.  
  65.       P4. Sometimes promoted screens need to be shifted horizontally in
  66.           order to be centered.
  67.  
  68.    PKludge was designed to provide a solution to the above problems by:
  69.  
  70.       S1. Allowing the promotion of any mode to any other mode.
  71.  
  72.       S2. Allowing a change of resolution during mode promotion.
  73.  
  74.       S3. Allowing per-application as well as per-mode promotion.
  75.  
  76.       S4. Allowing screens to be re-positioned during mode promotion.
  77.  
  78.       S5. Allowing the use of the same scan rate for all screens so that
  79.           partially obscured depth arranged screens don't look odd.
  80.  
  81.    Why is PKludge a kludge?  Because:
  82.  
  83.       * It was written in haste in order to have a solution to these
  84.         problems.  Its free, and you get what you pay for.
  85.  
  86.       * It is a bit unfriendly.  Mode promotion strings are cryptic and
  87.         only basic error checking is performed.  Little error checking is
  88.         done, and you can screw things up if you try.
  89.  
  90.       * Some applications may not like screens of other resolutions.
  91.         PKludge makes no attempt to do anything about this other than to
  92.         allow application specific mode promotion.
  93.  
  94.       * The need for PKludge should go away once all applications support
  95.         the display database.  Therefore, I'm not worried about making
  96.         this into something more real.
  97.  
  98.    PKludge is a commodity and can be disabled or killed with the Commodity
  99.    Exchange.  It does not have a fancy graphical user interface.  Instead,
  100.    it is controlled via cryptic workbench icon tooltypes or command line
  101.    arguments.  It should be installed in the WBStartup directory.  The
  102.    supported tooltypes are:
  103.  
  104.       CX_PRIORITY=<n>
  105.       PROMOTE=<title>/<o_mode>=<n_mode>/<left>/<top>/<width>/<height>/<oscan>
  106.  
  107.    The PROMOTE tooltype is the only interesting one.  It sounds more
  108.    complex than it is - the example section below should make it clear.
  109.  
  110.    PKludge works as follows: It intercepts open screen calls and checks
  111.    them against its list of screen names and modes.  If it finds a match,
  112.    it substitutes the new values (to the right of the 2nd "=" sign), and
  113.    then opens the screen.  If it finds no match, the screen is opened as
  114.    expected.
  115.  
  116.    WARNING:  If you don't know what you are doing, you can cause
  117.    applications to crash.  It is best to understand what you are promoting
  118.    to what in order to avoid confusing applications.  Some good rules to
  119.    follow are given later on.
  120.  
  121.    A "-" may be used for any of the items in the promotion mode string.
  122.    This signifies either "don't care", in the matching fields, or "don't
  123.    modify", in the substitution fields.  The two mode strings must
  124.    literally match the mode string from the display database, except for
  125.    case.  You can use the "ScreenMode" preferences tool to browse these
  126.    display mode strings.  The title string is taken from either the
  127.    screen's public screen name, if it has one, or the screen's title, if
  128.    it doesn't.  A smaller substring may be used, since some screen titles
  129.    can get rather long.  For example, the string "excellence!" matches the
  130.    64-odd character title used by Excellence 2.0 which begins with the
  131.    string "Excellence!".  Case does not matter.
  132.  
  133.    When searching mode promotion strings, the first match is used.  For
  134.    this reason, it is better to put screen specific promotion tooltypes
  135.    before mode-wide promotion tooltypes.
  136.  
  137.    PKludge can be stopped with the Commodity Exchange, or by double
  138.    clicking again on its workbench icon.  If it detects an error when run
  139.    from workbench, it exits with no error message.  (Remember the part
  140.    about this being a kludge? :-) ).  If launched from the CLI, it uses
  141.    its command line parameters as tooltypes, and will set a return code as
  142.    listed below.
  143.  
  144.  
  145. EXAMPLES
  146.  
  147.    Here are some examples of mode promotion strings.  Hopefully they will
  148.    be more clear than the above text was.
  149.  
  150.    PROMOTE=-/NTSC:High Res Laced=SUPER72:Super-High Res Laced/100/-/-/-/-
  151.  
  152.      This promotes any Amiga high res interlace screen (usually 640x400)
  153.      to SUPER72 super high res laced mode, in the same 640x400 resolution.
  154.      99% of applications should like this new mode just fine since it is
  155.      the same resolution.  However, it won't cause the monitor to jump
  156.      if your workbench is also in SUPER72 mode because the new screen will
  157.      be opened with the same scan rate.  Note than the 640x400 screen will
  158.      be smaller when viewed on the 800x600 or greater resolution of
  159.      SUPER72 super high res laced mode.  For this reason, the "100" for
  160.      the left edge modes the screen right a bit to center it on the
  161.      monitor.  You can adjust this value to suite your needs.
  162.  
  163.    PROMOTE=-/NTSC:High Res=SUPER72:Super-High Res/100/-/-/-/-
  164.  
  165.      This is the same as the above, but for non-interlace.  In general,
  166.      you want to promote screens to the same aspect ratio as they were
  167.      before.
  168.  
  169.    PROMOTE=excellence!/-=SUPER72:Super-High Res Laced/-/-/896/628/MAX
  170.  
  171.      Promotes a screen who's title begins with "excellence!" to 896x628
  172.      resolution using MAX overscan.  This is a good example of an
  173.      application (Excellence! 2.0) which can operate on larger screens
  174.      just fine, but only lacks the ability to open them.  Be careful: Some
  175.      applications may not be this forgiving of new screen modes.  In
  176.      general, applications which open windows on their screen which can be
  177.      resized will probably work OK.  Applications which make intimate
  178.      assumptions about the size of their screen probably won't.
  179.  
  180.  
  181.    In general, there are some rules you can follow which will make life
  182.    easier.  These are just rules of thumb; they're not hard and fast:
  183.  
  184.    R1. You can usually promote a screen to a mode of a higher resolution
  185.        and keep the size the same.  For example, you can promote all
  186.        640x400 screens to 800x600 SUPER72 mode, shift them right, keep
  187.        them in 640x400 size, and most applications should continue to work
  188.        fine.  As long as they get the same *size* screen, they will
  189.        probably be happy.
  190.  
  191.    R2. Applications which can deal with differently sized screens can
  192.        probably be promoted to higher resolution modes.  For example, I
  193.        tried the freeware program "Gravity-Well" (which simulates
  194.        celestial mechanics) and it works fine when promoted to 896x628.
  195.        It just can't open a screen that big by itself, since it dates back
  196.        to AmigaDos 1.3.
  197.  
  198.    R3. Don't "down-promote" screens to smaller sizes than the application
  199.        expects.  For example, don't promote a 640x400 screen to a 320x200
  200.        mode.
  201.  
  202.    R4. Try to promote modes to other modes of similar aspect ratios.  For
  203.        example, it works OK to promote 640x400 (1.6) to 800x600 (1.3), but
  204.        it doesn't work well to promote it to 640x800 (0.8).
  205.  
  206.    R5. Put screen-name specific promotion tooltypes _before_ general mode
  207.        promotion tooltypes.  This will allow PKludge to see them first.
  208.        You can use both a screen title and an original mode together, in
  209.        which case both must match.
  210.  
  211.    R6. Don't use odd values for sizes or positions.  PKludge doesn't do
  212.        much sanity checking.  You can certainly screw it up if you try.
  213.  
  214.  
  215. RETURN VALUES
  216.  
  217.    16    - The old mode string was not found in the display database.
  218.  
  219.    17    - The new mode string was not found in the display database.
  220.  
  221.    18    - An invalid PROMOTE tooltype format was found.
  222.  
  223.    19    - Can't create a message port.  Out of memory?
  224.  
  225.    20    - Can't open an AmigaDos library.  PKludge needs V39 libraries,
  226.            as used by AmigaDos 3.0 or later.  It won't run under 2.04.
  227.  
  228.  
  229. KNOWN BUGS
  230.  
  231.    B1. PKludge SetFunction()'s the OpenScreenTagList() function.  If another
  232.        program also setfunction's this *after* PKludge starts, and then
  233.        PKludge exits first, it will crash.  Workaround: don't do this.
  234.        Quit the 2nd application first.
  235.  
  236.    B2. PKludge doesn't do much sanity checking on the mode promotion
  237.        description strings.  You can probably fool it easily and produce
  238.        unwanted results, perhaps even crashing your system.
  239.  
  240.    B3. There is no GUI.  Tooltypes are awkward for this sort of input.  But
  241.        since the need for this program should go away eventually, I doubt
  242.        I'll fix this.
  243.  
  244.    B4. There can only be 64 PROMOTE tooltypes.  PKludge doesn't check for this
  245.        and you can trash memory if you give it more than that.
  246.        Workaround: don't do that.  Limit yourself to 64.
  247.  
  248.    B5. Although PKludge understands CLI arguments, it doesn't print a help
  249.        message and isn't very forgiving if you make mistakes.  I suppose
  250.        I've mentioned already that this is free and worth just about what
  251.        you payed for it.
  252.  
  253.  
  254. BUG REPORTS
  255.  
  256.    Send bug reports to me at:
  257.  
  258.    Steve Koren
  259.    405 Pulsar St.
  260.    Fort Collins, CO 80525 USA
  261.  
  262.    303-226-4985 (USA)
  263.  
  264.    I may or may not fix them.  Can't hurt to try though.
  265.